<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="topic1">
      <title>plcontainer Configuration File</title>
      <body>
                <p>The Greenplum Database utility <codeph>plcontainer</codeph> manages the
                    PL/Container configuration files in a Greenplum Database system. The utility
                    ensures that the configuration files are consistent across the Greenplum
                    Database master and segment instances.</p>
                <note type="warning"> Modifying the configuration files on the segment instances
                    without using the utility might create different, incompatible configurations on
                    different Greenplum Database segments that could cause unexpected behavior. </note>
                <section id="topic_ojn_r2s_dw"><title>PL/Container Configuration File</title>
                    <p>PL/Container maintains a configuration file
                            <codeph>plcontainer_configuration.xml</codeph> in the data directory of
                        all Greenplum Database segments. This query lists the Greenplum Database
                        system data directories:
                    </p><codeblock>SELECT hostname, datadir FROM gp_segment_configuration;</codeblock>
                    A sample PL/Container configuration file is in
                        <codeph>$GPHOME/share/postgresql/plcontainer</codeph>. <p>In an XML file,
                        names, such as element and attribute names, and values are case
                        sensitive.</p>In this XML file, the root element
                        <codeph>configuration</codeph> contains one or more <codeph>runtime</codeph>
                    elements. You specify the <codeph>id</codeph> of the <codeph>runtime</codeph>
                    element in the <codeph># container:</codeph> line of a PL/Container function
                    definition. <p>This is an example file. Note that all XML elements, names, and
                        attributes are case
                        sensitive.<codeblock>&lt;?xml version="1.0" ?>
&lt;configuration>
    &lt;runtime>
        &lt;id>plc_python_example1&lt;/id>
        &lt;image>pivotaldata/plcontainer_python_with_clients:0.1&lt;/image>
        &lt;command>./pyclient&lt;/command>
    &lt;/runtime>
    &lt;runtime>
        &lt;id>plc_python_example2&lt;/id>
        &lt;image>pivotaldata/plcontainer_python_without_clients:0.1&lt;/image>
        &lt;command>/clientdir/pyclient.sh&lt;/command>
        &lt;shared_directory access="ro" container="/clientdir" host="/usr/local/greenplum-db/bin/plcontainer_clients"/>
        &lt;setting memory_mb="512"/>
        &lt;setting use_container_logging="yes"/>
        &lt;setting cpu_share="1024"/>
        &lt;setting resource_group_id="16391"/>
    &lt;/runtime>
    &lt;runtime>
        &lt;id>plc_r_example&lt;/id>
        &lt;image>pivotaldata/plcontainer_r_without_clients:0.2&lt;/image>
        &lt;command>/clientdir/rclient.sh&lt;/command>
        &lt;shared_directory access="ro" container="/clientdir" host="/usr/local/greenplum-db/bin/plcontainer_clients"/>
        &lt;setting use_container_logging="yes"/>
        &lt;setting roles="gpadmin,user1"/>
    &lt;/runtime>
    &lt;runtime>
&lt;/configuration></codeblock></p><p>These
                        are the XML elements and attributes in a PL/Container configuration
                        file.</p><parml>
                        <plentry>
                            <pt>configuration</pt>
                            <pd>Root element for the XML file.</pd>
                        </plentry>
                        <plentry>
                            <pt>runtime</pt>
                            <pd>One element for each specific container available in the system.
                                These are child elements of the <codeph>configuration</codeph>
                                element.</pd>
                            <pd>
                                <parml>
                                    <plentry>
                                        <pt>id</pt>
                                        <pd>Required. The value is used to reference a Docker
                                            container from a PL/Container user-defined function. The
                                                <codeph>id</codeph> value must be unique in the
                                            configuration. The <codeph>id</codeph> must start with a
                                            character or digit (a-z, A-Z, or 0-9) and can contain
                                            characters, digits, or the characters <codeph>_</codeph>
                                            (underscore), <codeph>.</codeph> (period), or
                                                <codeph>-</codeph> (dash). Maximum length is 63
                                                Bytes.<p>The <codeph>id</codeph> specifies which
                                                Docker image to use when PL/Container creates a
                                                Docker container to run a user-defined
                                                function.</p></pd>
                                    </plentry>
                                    <plentry>
                                        <pt>image</pt>
                                        <pd>
                                            <p>Required. The value is the full Docker image name,
                                                including image tag. The same way you specify them
                                                for starting this container in Docker. Configuration
                                                allows to have many container objects referencing
                                                the same image name, this way in Docker they would
                                                be represented by identical containers. </p>
                                            <p>For example, you might have two
                                                  <codeph>runtime</codeph> elements, with different
                                                  <codeph>id</codeph> elements,
                                                  <codeph>plc_python_128</codeph> and
                                                  <codeph>plc_python_256</codeph>, both referencing
                                                the Docker image
                                                  <codeph>pivotaldata/plcontainer_python:1.0.0</codeph>.
                                                The first <codeph>runtime</codeph> specifies a 128MB
                                                RAM limit and the second one specifies a 256MB limit
                                                that is specified by the <codeph>memory_mb</codeph>
                                                attribute of a <codeph>setting</codeph> element.</p>
                                        </pd>
                                    </plentry>
                                    <plentry>
                                        <pt>command</pt>
                                        <pd>Required. The value is the command to be run inside of
                                            container to start the client process inside in the
                                            container. When creating a <codeph>runtime</codeph>
                                            element, the <codeph>plcontainer</codeph> utility adds a
                                                <codeph>command</codeph> element based on the
                                            language (the <codeph>-l</codeph> option).</pd>
                                        <pd><codeph>command</codeph> element for the Python 2
                                            language.<codeblock>&lt;command>/clientdir/pyclient.sh&lt;/command></codeblock></pd>
                                        <pd><codeph>command</codeph> element for the Python 3
                                            language.<codeblock>&lt;command>/clientdir/pyclient3.sh&lt;/command></codeblock></pd>
                                        <pd><codeph>command</codeph> element for the R
                                            language.<codeblock>&lt;command>/clientdir/rclient.sh&lt;/command></codeblock></pd>
                                        <pd>You should modify the value only if you build a custom
                                            container and want to implement some additional
                                            initialization logic before the container starts.
                                                <note>This element cannot be set with the
                                                  <codeph>plcontainer</codeph> utility. You can
                                                update the configuration file with the
                                                  <codeph>plcontainer runtime-edit</codeph>
                                                command.</note></pd>
                                    </plentry>
                                    <plentry>
                                        <pt>shared_directory</pt>
                                        <pd>Optional. This element specifies a shared Docker shared
                                            volume for a container with access information. Multiple
                                                <codeph>shared_directory</codeph> elements are
                                            allowed. Each <codeph>shared_directory</codeph> element
                                            specifies a single shared volume. XML attributes for the
                                                <codeph>shared_directory</codeph> element:<ul
                                                id="ul_x4d_lcs_dw">
                                                <li><codeph>host</codeph> - a directory location on
                                                  the host system.</li>
                                                <li><codeph>container</codeph> - a directory
                                                  location inside of container.</li>
                                                <li><codeph>access</codeph> - access level to the
                                                  host directory, which can be either
                                                  <codeph>ro</codeph> (read-only) or
                                                  <codeph>rw</codeph> (read-write). </li>
                                            </ul></pd>
                                        <pd>When creating a <codeph>runtime</codeph> element, the
                                                <codeph>plcontainer</codeph> utility adds a
                                                <codeph>shared_directory</codeph>
                                            element.<codeblock>&lt;shared_directory access="ro" container="/clientdir" host="/usr/local/greenplum-db/bin/plcontainer_clients"/></codeblock></pd>
                                        <pd>For each <codeph>runtime</codeph> element, the
                                                <codeph>container</codeph> attribute of the
                                                <codeph>shared_directory</codeph> elements must be
                                            unique. For example, a <codeph>runtime</codeph> element
                                            cannot have two <codeph>shared_directory</codeph>
                                            elements with attribute
                                                <codeph>container="/clientdir"</codeph>. <note
                                                type="warning">Allowing read-write access to a host
                                                directory requires special consideration.<ul
                                                  id="ul_vzb_dvk_kcb">
                                                  <li>When specifying read-write access to host
                                                  directory, ensure that the specified host
                                                  directory has the correct permissions. </li>
                                                  <li>When running PL/Container user-defined
                                                  functions, multiple concurrent Docker containers
                                                  that are running on a host could change data in
                                                  the host directory. Ensure that the functions
                                                  support multiple concurrent access to the data in
                                                  the host directory.</li>
                                                </ul></note></pd>
                                    </plentry>
                                    <plentry id="plc_settings">
                                        <pt>settings</pt>
                                        <pd>Optional. This element specifies Docker container
                                            configuration information. Each <codeph>setting</codeph>
                                            element contains one attribute. The element attribute
                                            specifies logging, memory, or networking information.
                                            For example, this element enables
                                            logging.<codeblock>&lt;setting use_container_logging="yes"/></codeblock></pd>
                                        <pd>These are the valid attributes.<parml>
                                                <plentry>
                                                  <pt>cpu_share</pt>
                                                  <pd>Optional. Specify the CPU usage for each
                                                  PL/Container container in the runtime. The value
                                                  of the element is a positive integer. The default
                                                  value is 1024. The value is a relative weighting
                                                  of CPU usage compared to other containers. </pd>
                                                  <pd>For example, a container with a
                                                  <codeph>cpu_share</codeph> of 2048 is allocated
                                                  double the CPU slice time compared with container
                                                  with the default value of 1024.</pd>
                                                </plentry>
                                                <plentry>
                                                  <pt>memory_mb="<varname>size</varname>"</pt>
                                                  <pd>Optional. The value specifies the amount of
                                                  memory, in MB, that each container is allowed to
                                                  use. Each container starts with this amount of RAM
                                                  and twice the amount of swap space. The container
                                                  memory consumption is limited by the host system
                                                  <codeph>cgroups</codeph> configuration, which
                                                  means in case of memory overcommit, the container
                                                  is terminated by the system.</pd>
                                                </plentry>
                                                <plentry>
                                                  <pt>resource_group_id="<varname>rg_groupid</varname>"</pt>
                                                  <pd>Optional. The value specifies the
                                                  <codeph>groupid</codeph> of the resource group to
                                                assign to the PL/Container runtime. The resource
                                                group limits the total CPU and memory resource usage
                                                for all running containers that share this runtime
                                                configuration. You must specify the
                                                  <codeph>groupid</codeph> of the resource group. If
                                                you do not assign a resource group to a PL/Container
                                                runtime configuration, its container instances are
                                                limited only by system resources. For information
                                                about managing PL/Container resources, see <xref
                                                  href="../../analytics/pl_container_using.html#topic_resmgmt"
                                                  format="html" scope="external">About PL/Container Resource
                                                  Management</xref>.</pd>
                                                </plentry>
                                                <plentry>
                                                  <pt>roles="<varname>list_of_roles</varname>"</pt>
                                                  <pd>Optional. The value is a Greenplum Database
                                                  role name or a comma-separated list of roles.
                                                  PL/Container runs a container that uses the
                                                  PL/Container runtime configuration only for the
                                                  listed roles. If the attribute is not specified,
                                                  any Greenplum Database role can run an instance of
                                                  this container runtime configuration. For example,
                                                  you create a UDF that specifies the
                                                  <codeph>plcontainer</codeph> language and
                                                  identifies a <codeph># container:</codeph> runtime
                                                  configuration that has the <codeph>roles</codeph>
                                                  attribute set. When a role (user) runs the UDF,
                                                  PL/Container checks the list of roles and runs the
                                                  container only if the role is on the list.</pd>
                                                </plentry>
                                                <plentry>
                                                  <pt> use_container_logging="{yes | no}"</pt>
                                                  <pd>Optional. Enables or disables Docker logging
                                                  for the container. The attribute value
                                                  <codeph>yes</codeph> enables logging. The
                                                  attribute value <codeph>no</codeph> disables
                                                  logging (the default). </pd>
                                                  <pd>The Greenplum Database server configuration
                                                parameter <xref
                                                  href="../../ref_guide/config_params/guc-list.xml#log_min_messages"
                                                  scope="local">log_min_messages</xref> controls the
                                                PL/Container log level. The default log level is
                                                  <codeph>warning</codeph>. For information about
                                                PL/Container log information, see <xref
                                                  href="../../analytics/pl_container_using.html#plc_notes"
                                                  format="html" scope="external">Notes</xref>.</pd>
                                                  <pd>
                                                  <p>By default, the PL/Container log information is
                                                  sent to a system service. On Red Hat 7 or CentOS 7
                                                  systems, the log information is sent to the
                                                  <codeph>journald</codeph> service. On Red Hat 6 or
                                                  CentOS 6 systems, the log is sent to the
                                                  <codeph>syslogd</codeph> service. </p>
                                                  </pd>
                                                </plentry>
                                            </parml></pd>
                                    </plentry>
                                </parml>
                            </pd>
                        </plentry>
                    </parml>
                </section>
                <section id="topic_v3s_qv3_kw">
                    <title>Update the PL/Container Configuration</title>
                    <p>You can add a <codeph>runtime</codeph> element to the PL/Container
                        configuration file with the <codeph>plcontainer runtime-add</codeph>
                        command. The command options specify information such as the runtime ID,
                        Docker image, and language. You can use the <codeph>plcontainer
                            runtime-replace</codeph> command to update an existing
                            <codeph>runtime</codeph> element. The utility updates the configuration
                        file on the master and all segment instances.</p>
                    <p>The PL/Container configuration file can contain multiple
                            <codeph>runtime</codeph> elements that reference the same Docker image
                        specified by the XML element <codeph>image</codeph>. In the example
                        configuration file, the <codeph>runtime</codeph> elements contain
                            <codeph>id</codeph> elements named <codeph>plc_python_128</codeph> and
                            <codeph>plc_python_256</codeph>, both referencing the Docker container
                            <codeph>pivotaldata/plcontainer_python:1.0.0</codeph>. The first
                            <codeph>runtime</codeph> element is defined with a 128MB RAM limit and
                        the second one with a 256MB RAM limit.</p>
                    <codeblock>&lt;configuration>
  &lt;runtime>
    &lt;id>plc_python_128&lt;/id>
    &lt;image>pivotaldata/plcontainer_python:1.0.0&lt;/image>
    &lt;command>./client&lt;/command>
    &lt;shared_directory access="ro" container="/clientdir" host="/usr/local/gpdb/bin/plcontainer_clients"/>
    &lt;setting memory_mb="128"/>
  &lt;/runtime>
  &lt;runtime>
    &lt;id>plc_python_256&lt;/id>
    &lt;image>pivotaldata/plcontainer_python:1.0.0&lt;/image>
    &lt;command>./client&lt;/command>
    &lt;shared_directory access="ro" container="/clientdir" host="/usr/local/gpdb/bin/plcontainer_clients"/>
    &lt;setting memory_mb="256"/>
    &lt;setting resource_group_id="16391"/>
  &lt;/runtime>
&lt;configuration></codeblock>
                    <p>Configuration changes that are made with the utility are applied to the XML
                        files on all Greenplum Database segments. However, PL/Container
                        configurations of currently running sessions use the configuration that
                        existed during session start up. To update the PL/Container configuration in
                        a running session, run this command in the session.</p>
                    <codeblock>SELECT * FROM plcontainer_refresh_config;</codeblock>
                    <p>The command runs a PL/Container function that updates the session
                        configuration on the master and segment instances.</p>
                </section>
        
  
      </body>
    </topic>
